<!DOCTYPE html>
<html>

<head>
  <title>Quarkus - Sending emails</title>
  <script id="adobe_dtm" src="https://www.redhat.com/dtm.js" type="text/javascript"></script>
  <script src="/assets/javascript/highlight.pack.js" type="text/javascript"></script>
  <META HTTP-EQUIV='Content-Security-Policy' CONTENT="default-src 'none'; script-src 'self' 'unsafe-eval' 'sha256-ANpuoVzuSex6VhqpYgsG25OHWVA1I+F6aGU04LoI+5s=' 'sha256-ipy9P/3rZZW06mTLAR0EnXvxSNcnfSDPLDuh3kzbB1w=' js.bizographics.com https://www.redhat.com assets.adobedtm.com jsonip.com https://ajax.googleapis.com https://www.googletagmanager.com https://www.google-analytics.com https://use.fontawesome.com; style-src 'self' https://fonts.googleapis.com https://use.fontawesome.com; img-src 'self' *; media-src 'self' ; frame-src https://www.googletagmanager.com https://www.youtube.com; frame-ancestors 'none'; base-uri 'none'; object-src 'none'; form-action 'none'; font-src 'self' https://use.fontawesome.com https://fonts.gstatic.com;">
  <META HTTP-EQUIV='X-Frame-Options' CONTENT="DENY">
  <META HTTP-EQUIV='X-XSS-Protection' CONTENT="1; mode=block">
  <META HTTP-EQUIV='X-Content-Type-Options' CONTENT="nosniff">
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <meta name="description" content="Quarkus: Supersonic Subatomic Java">
  <meta name="twitter:card" content="summary_large_image">
  <meta name="twitter:site" content="@QuarkusIO"> 
  <meta name="twitter:creator" content="@QuarkusIO">
  <meta property="og:url" content="https://quarkus.io/guides/mailer" />
  <meta property="og:title" content="Quarkus - Sending emails" />
  <meta property="og:description" content="Quarkus: Supersonic Subatomic Java" />
  <meta property="og:image" content="/assets/images/quarkus_card.png" />
  <link rel="canonical" href="https://quarkus.io/guides/mailer">
  <link rel="shortcut icon" type="image/png" href="/favicon.ico" >
  <link rel="stylesheet" href="https://quarkus.io/guides/stylesheet/config.css" />
  <link rel="stylesheet" href="/assets/css/main.css" />
  <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.1.0/css/all.css" integrity="sha384-lKuwvrZot6UHsBSfcMvOkWwlCMgc0TaWr+30HWe3a4ltaBwTZhyTEggF5tJv8tbt" crossorigin="anonymous">
  <link rel="alternate" type="application/rss+xml"  href="https://quarkus.io/feed.xml" title="Quarkus">
  <script src="https://quarkus.io/assets/javascript/goan.js" type="text/javascript"></script>
  <script src="https://quarkus.io/assets/javascript/hl.js" type="text/javascript"></script>
</head>

<body class="guides">
  <!-- Google Tag Manager (noscript) -->
  <noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-NJWS5L"
  height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
  <!-- End Google Tag Manager (noscript) -->

  <div class="nav-wrapper">
  <div class="grid-wrapper">
    <div class="width-12-12">
      <input type="checkbox" id="checkbox" />
      <nav id="main-nav" class="main-nav">
  <div class="container">
    <div class="logo-wrapper">
      
        <a href="/"><img src="/assets/images/quarkus_logo_horizontal_rgb_600px_reverse.png" class="project-logo" title="Quarkus"></a>
      
    </div>
    <label class="nav-toggle" for="checkbox">
      <i class="fa fa-bars"></i>
    </label>
    <div id="menu" class="menu">
      <span>
        <a href="/get-started/" class="">Get Started</a>
      </span>
      <span>
        <a href="/guides/" class="active">Guides</a>
      </span>
      <span>
        <a href="/community/" class="">Community</a>
      </span>
      <span>
        <a href="/support/" class="">Support</a>
      </span>
      <span>
        <a href="/blog/" class="">Blog</a>
      </span>
      <span>
        <a href="https://code.quarkus.io" class="button-cta secondary white">Start Coding</a>
      </span>
    </div>
  </div>
      </nav>
    </div>
  </div>
</div>

  <div class="content">
    <div class="guide">
  <div class="width-12-12">
    <h1 class="text-caps">Quarkus - Sending emails</h1>
    <div class="hide-mobile toc"><ul class="sectlevel1">
<li><a href="#prerequisites">Prerequisites</a></li>
<li><a href="#architecture">Architecture</a></li>
<li><a href="#creating-the-maven-project">Creating the Maven Project</a></li>
<li><a href="#configuring-the-mailer">Configuring the mailer</a></li>
<li><a href="#sending-simple-emails">Sending simple emails</a></li>
<li><a href="#sending-attachments">Sending attachments</a></li>
<li><a href="#sending-html-emails-with-inlined-attachments">Sending HTML emails with inlined attachments</a></li>
<li><a href="#message-body-based-on-qute-templates">Message Body Based on Qute Templates</a></li>
<li><a href="#testing-email-sending">Testing email sending</a></li>
<li><a href="#gmail-specific-configuration">Gmail specific configuration</a></li>
<li><a href="#using-ssl-with-native-executables">Using SSL with native executables</a></li>
<li><a href="#using-the-underlying-vert-x-mail-client">Using the underlying Vert.x Mail Client</a></li>
<li><a href="#conclusion">Conclusion</a></li>
<li><a href="#configuration-reference">Mailer Configuration Reference</a></li>
</ul></div>
    <div>
      <div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>This guide demonstrates how your Quarkus application can send emails using an SMTP server.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="prerequisites"><a class="anchor" href="#prerequisites"></a>Prerequisites</h2>
<div class="sectionbody">
<div class="paragraph">
<p>To complete this guide, you need:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>less than 15 minutes</p>
</li>
<li>
<p>The SMTP hostname, port and credentials, and an email address</p>
</li>
<li>
<p>an IDE</p>
</li>
<li>
<p>JDK 1.8+ installed with <code>JAVA_HOME</code> configured appropriately</p>
</li>
<li>
<p>Apache Maven 3.6.2+</p>
</li>
<li>
<p>GraalVM installed if you want to run in native mode.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="architecture"><a class="anchor" href="#architecture"></a>Architecture</h2>
<div class="sectionbody">
<div class="paragraph">
<p>In this guide, we are going to see how you can send emails from a Quarkus application.
It covers simple emails, attachments, inlined attachments, the reactive and imperative APIs&#8230;&#8203;</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="creating-the-maven-project"><a class="anchor" href="#creating-the-maven-project"></a>Creating the Maven Project</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Create a new project with the following command:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-none hljs">mvn io.quarkus:quarkus-maven-plugin:1.7.0.Final:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=sending-email-quickstart \
    -Dextensions="mailer"
cd sending-email-quickstart</code></pre>
</div>
</div>
<div class="paragraph">
<p>If you already have an existing project, add the <code>mailer</code> extension:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-none hljs">./mvnw quarkus:add-extensions -Dextensions="mailer"</code></pre>
</div>
</div>
<div class="paragraph">
<p>This will add the following to your <code>pom.xml</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="xml" class="language-xml hljs">&lt;dependency&gt;
    &lt;groupId&gt;io.quarkus&lt;/groupId&gt;
    &lt;artifactId&gt;quarkus-mailer&lt;/artifactId&gt;
&lt;/dependency&gt;</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="configuring-the-mailer"><a class="anchor" href="#configuring-the-mailer"></a>Configuring the mailer</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The Quarkus mailer is using SMTP. In the <code>src/main/resources/application.properties</code> file, you need to configure the host, port, username, password as well as the other configuration aspect.
Note that the password can also be configured using system properties and environment variables.</p>
</div>
<div class="paragraph">
<p>Here is an example using <em>sendgrid</em>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-none hljs">quarkus.mailer.from=test@quarkus.io
quarkus.mailer.host=smtp.sendgrid.net
quarkus.mailer.port=465
quarkus.mailer.ssl=true
quarkus.mailer.username=....
quarkus.mailer.password=....
quarkus.mailer.mock=false</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>It is recommended to encrypt any sensitive data, such as the <code>quarkus.mailer.password</code>.
One approach is to save the value into a secure store like HashiCorp Vault, and refer to it from the configuration.
Assuming for instance that Vault contains key <code>mail-password</code> at path <code>myapps/myapp/myconfig</code>, then the mailer
extension can be simply configured as:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-none hljs">...
# path within the kv secret engine where is located the application sensitive configuration
quarkus.vault.secret-config-kv-path=myapps/myapp/myconfig

...
quarkus.mailer.password=${mail-password}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Please note that the password value is evaluated only once, at startup time. If <code>mail-password</code> was changed in Vault,
the only way to get the new value would be to restart the application.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
For more information about the Mailer extension configuration please refer to the <a href="#configuration-reference">Configuration Reference</a>.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="sending-simple-emails"><a class="anchor" href="#sending-simple-emails"></a>Sending simple emails</h2>
<div class="sectionbody">
<div class="paragraph">
<p>In a JAX-RS resource, or in a bean, you can inject the mailer as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="java" class="language-java hljs">@Inject
Mailer mailer;

@Inject
ReactiveMailer reactiveMailer;</code></pre>
</div>
</div>
<div class="paragraph">
<p>There are 2 APIs:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>io.quarkus.mailer.Mailer</code> provides the imperative (blocking and synchronous) API;</p>
</li>
<li>
<p><code>io.quarkus.mailer.reactive.ReactiveMailer</code> provides the reactive (non-blocking and asynchronous) API</p>
</li>
</ul>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The two APIs are equivalent feature-wise. Actually the <code>Mailer</code> implementation is built on top of the <code>ReactiveMailer</code> implementation.
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="title">Deprecation</div>
<div class="paragraph">
<p><code>io.quarkus.mailer.ReactiveMailer</code> is deprecated in favor of <code>io.quarkus.mailer.reactive.ReactiveMailer</code>.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
<div class="title">Mutiny</div>
<div class="paragraph">
<p>The reactive mailer uses Mutiny reactive types, if you&#8217;re not familiar with them, read the <a href="getting-started-reactive#mutiny">Getting Started with Reactive guide</a> first.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>To send a simple email, proceed as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="java" class="language-java hljs">// Imperative API:
mailer.send(Mail.withText("to@acme.org", "A simple email from quarkus", "This is my body."));
// Reactive API:
Uni&lt;Void&gt; stage = reactiveMailer.send(Mail.withText("to@acme.org", "A reactive email from quarkus", "This is my body."));</code></pre>
</div>
</div>
<div class="paragraph">
<p>For example, you can use the <code>Mailer</code> in a JAX-RS endpoint as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="java" class="language-java hljs">@GET
@Path("/simple")
public Response sendASimpleEmail() {
    mailer.send(Mail.withText("to@acme.org", "A simple email from quarkus", "This is my body"));
    return Response.accepted().build();
}

@GET
@Path("/async")
public CompletionStage&lt;Response&gt; sendASimpleEmailAsync() {
    return reactiveMailer.send(
            Mail.withText("to@acme.org", "A reactive email from quarkus", "This is my body"))
            .subscribeAsCompletionStage()
            .thenApply(x -&gt; Response.accepted().build());
}</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>With the <code>quarkus-resteasy-mutiny</code> extension, you can return an instance of <code>Uni</code> directly.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>With such a JAX-RS resource, you can check that everything is working with:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="bash" class="language-bash hljs">curl http://localhost:8080/simple
curl http://localhost:8080/async</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can create new <code>io.quarkus.mailer.Mail</code> instances from the constructor or from the <code>Mail.withText</code> and
<code>Mail.withHtml</code> helper methods. The <code>Mail</code> instance lets you add recipients (to, cc, or bcc), set the subject,
headers, sender (from) address&#8230;&#8203;</p>
</div>
<div class="paragraph">
<p>You can also send several <code>Mail</code> objects in one call:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="java" class="language-java hljs">mailer.send(mail1, mail2, mail3);</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="sending-attachments"><a class="anchor" href="#sending-attachments"></a>Sending attachments</h2>
<div class="sectionbody">
<div class="paragraph">
<p>To send attachment, just use the <code>addAttachment</code> methods on the <code>io.quarkus.mailer.Mail</code> instance:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="java" class="language-java hljs">@GET
@Path("/attachment")
public Response sendEmailWithAttachment() {
    mailer.send(Mail.withText("to@acme.org", "An email from quarkus with attachment",
            "This is my body")
            .addAttachment("my-file.txt",
                "content of my file".getBytes(), "text/plain"));
    return Response.accepted().build();
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Attachments can be created from raw bytes (as shown in the snippet) or files.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="sending-html-emails-with-inlined-attachments"><a class="anchor" href="#sending-html-emails-with-inlined-attachments"></a>Sending HTML emails with inlined attachments</h2>
<div class="sectionbody">
<div class="paragraph">
<p>When sending HTML email, you can add inlined attachments.
For example, you can send an image with your email, and this image will be displayed in the mail content. If you put the image file into resources folder, you should specify the full path to the file. "e.g." "META-INF/resources/quarkus-logo.png" otherwise quarkus will lookup in the root folder of the project</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="java" class="language-java hljs">@GET
@Path("/html")
public Response sendingHTML() {
    String body = "&lt;strong&gt;Hello!&lt;/strong&gt;" + "\n" +
        "&lt;p&gt;Here is an image for you: &lt;img src=\"cid:my-image@quarkus.io\"/&gt;&lt;/p&gt;" +
        "&lt;p&gt;Regards&lt;/p&gt;";
    mailer.send(Mail.withHtml("to@acme.org", "An email in HTML", body)
        .addInlineAttachment("quarkus-logo.png",
            new File("quarkus-logo.png"),
            "image/png", "&lt;my-image@quarkus.io&gt;"));
    return Response.accepted().build();
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note the <em>content-id</em> format and reference.
By spec, when you create the inline attachment, the content-id must be structured as follows: <code>&lt;id@domain&gt;</code>.
If you don&#8217;t wrap your content-id between <code>&lt;&gt;</code>, it is automatically wrapped for you.
When you want to reference your attachment, for instance in the <code>src</code> attribute, use <code>cid:id@domain</code> (without the <code>&lt;</code> and <code>&gt;</code>).</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="message-body-based-on-qute-templates"><a class="anchor" href="#message-body-based-on-qute-templates"></a>Message Body Based on Qute Templates</h2>
<div class="sectionbody">
<div class="paragraph">
<p>It&#8217;s also possible to inject a mail template, where the message body is created automatically using <a href="qute">Qute templates</a>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="java" class="language-java hljs">@Path("")
public class MailingResource {

    @CheckedTemplate
    class Templates {
        public static native MailTemplateInstance hello(String name); <i class="conum" data-value="1"></i><b>(1)</b>
    }

    @GET
    @Path("/mail")
    public CompletionStage&lt;Response&gt; send() {
        // the template looks like: Hello {name}! <i class="conum" data-value="2"></i><b>(2)</b>
        return Templates.hello("John")
           .to("to@acme.org") <i class="conum" data-value="3"></i><b>(3)</b>
           .subject("Hello from Qute template")
           .send() <i class="conum" data-value="4"></i><b>(4)</b>
           .subscribeAsCompletionStage()
           .thenApply(x -&gt; Response.accepted().build());
    }
}</code></pre>
</div>
</div>
<div class="colist arabic">
<table>
<tr>
<td><i class="conum" data-value="1"></i><b>1</b></td>
<td>By convention, the enclosing class name and method names are used to locate the template. In this particular case,
we will use the <code>MailingResource/hello.html</code> and <code>MailingResource/hello.txt</code> templates to create the message body.</td>
</tr>
<tr>
<td><i class="conum" data-value="2"></i><b>2</b></td>
<td>Set the data used in the template.</td>
</tr>
<tr>
<td><i class="conum" data-value="3"></i><b>3</b></td>
<td>Create a mail template instance and set the recipient.</td>
</tr>
<tr>
<td><i class="conum" data-value="4"></i><b>4</b></td>
<td><code>MailTemplate.send()</code> triggers the rendering and, once finished, sends the e-mail via a <code>Mailer</code> instance.</td>
</tr>
</table>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
Injected mail templates are validated during build. If there is no matching template in <code>src/main/resources/templates</code> the build fails.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>You can also do this without type-safe templates:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="java" class="language-java hljs">@Inject
MailTemplate hello; <i class="conum" data-value="1"></i><b>(1)</b>

@GET
@Path("/mail")
public CompletionStage&lt;Response&gt; send() {
    return hello.to("to@acme.org") <i class="conum" data-value="2"></i><b>(2)</b>
       .subject("Hello from Qute template")
       // the template looks like: Hello {name}!
       .data("name", "John") <i class="conum" data-value="3"></i><b>(3)</b>
       .send() <i class="conum" data-value="4"></i><b>(4)</b>
       .subscribeAsCompletionStage()
       .thenApply(x -&gt; Response.accepted().build());
}</code></pre>
</div>
</div>
<div class="colist arabic">
<table>
<tr>
<td><i class="conum" data-value="1"></i><b>1</b></td>
<td>If there is no <code>@ResourcePath</code> qualifier provided, the field name is used to locate the template. In this particular case, we will use the <code>hello.html</code> and <code>hello.txt</code> templates to create the message body.</td>
</tr>
<tr>
<td><i class="conum" data-value="2"></i><b>2</b></td>
<td>Create a mail template instance and set the recipient.</td>
</tr>
<tr>
<td><i class="conum" data-value="3"></i><b>3</b></td>
<td>Set the data used in the template.</td>
</tr>
<tr>
<td><i class="conum" data-value="4"></i><b>4</b></td>
<td><code>MailTemplate.send()</code> triggers the rendering and, once finished, sends the e-mail via a <code>Mailer</code> instance.</td>
</tr>
</table>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
Injected mail templates are validated during build. If there is no matching template in <code>src/main/resources/templates</code> the build fails.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="testing-email-sending"><a class="anchor" href="#testing-email-sending"></a>Testing email sending</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Because it is very inconvenient to send emails during development and testing, you can set the <code>quarkus.mailer.mock</code> boolean
configuration to <code>true</code> to not actually send emails but print them on stdout and collect them in a <code>MockMailbox</code> bean instead.
This is the default if you are running Quarkus in <code>DEV</code> or <code>TEST</code> mode.</p>
</div>
<div class="paragraph">
<p>You can then write tests to verify that your emails were sent, for example, by a REST endpoint:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="java" class="language-java hljs">@QuarkusTest
class MailTest {

    private static final String TO = "foo@quarkus.io";

    @Inject
    MockMailbox mailbox;

    @BeforeEach
    void init() {
        mailbox.clear();
    }

    @Test
    void testTextMail() throws MessagingException, IOException {
        // call a REST endpoint that sends email
        given()
        .when()
        .get("/send-email")
        .then()
           .statusCode(202)
           .body(is("OK"));

        // verify that it was sent
        List&lt;Mail&gt; sent = mailbox.getMessagesSentTo(TO);
        assertThat(sent).hasSize(1);
        Mail actual = sent.get(0);
        assertThat(actual.getText()).contains("Wake up!");
        assertThat(actual.getSubject()).isEqualTo("Alarm!");

        assertThat(mailbox.getTotalMessagesSent()).isEqualTo(6);
    }
}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="gmail-specific-configuration"><a class="anchor" href="#gmail-specific-configuration"></a>Gmail specific configuration</h2>
<div class="sectionbody">
<div class="paragraph">
<p>If you want to use the Gmail SMTP server, first create a dedicated password in <code>Google Account &gt; Security &gt; App passwords</code> or go to <a href="https://myaccount.google.com/apppasswords" class="bare">https://myaccount.google.com/apppasswords</a>.</p>
</div>
<div class="paragraph">
<p>When done, you can configure your Quarkus application by adding the following properties to your <code>application.properties</code>:</p>
</div>
<div class="paragraph">
<p>With TLS:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-none hljs">quarkus.mailer.auth-methods=DIGEST-MD5 CRAM-SHA256 CRAM-SHA1 CRAM-MD5 PLAIN LOGIN
quarkus.mailer.from=YOUREMAIL@gmail.com
quarkus.mailer.host=smtp.gmail.com
quarkus.mailer.port=587
quarkus.mailer.start-tls=REQUIRED
quarkus.mailer.username=YOUREMAIL@gmail.com
quarkus.mailer.password=YOURGENERATEDAPPLICATIONPASSWORD</code></pre>
</div>
</div>
<div class="paragraph">
<p>Or with SSL:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-none hljs">quarkus.mailer.auth-methods=DIGEST-MD5 CRAM-SHA256 CRAM-SHA1 CRAM-MD5 PLAIN LOGIN
quarkus.mailer.from=YOUREMAIL@gmail.com
quarkus.mailer.host=smtp.gmail.com
quarkus.mailer.port=465
quarkus.mailer.ssl=true
quarkus.mailer.username=YOUREMAIL@gmail.com
quarkus.mailer.password=YOURGENERATEDAPPLICATIONPASSWORD</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>The <code>quarkus.mailer.auth-methods</code> configuration option is needed for the Quarkus mailer to support password authentication with Gmail.
By default both the mailer and Gmail default to <code>XOAUTH2</code> which requires registering an application, getting tokens, etc.</p>
</div>
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="using-ssl-with-native-executables"><a class="anchor" href="#using-ssl-with-native-executables"></a>Using SSL with native executables</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Note that if you enable SSL for the mailer and you want to build a native executable, you will need to enable the SSL support.
Please refer to the <a href="native-and-ssl">Using SSL With Native Executables</a> guide for more information.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="using-the-underlying-vert-x-mail-client"><a class="anchor" href="#using-the-underlying-vert-x-mail-client"></a>Using the underlying Vert.x Mail Client</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The Quarkus Mailer is implemented on top of the <a href="https://vertx.io/docs/vertx-mail-client/java/">Vert.x Mail Client</a>, providing an asynchronous and non-blocking way to send emails.
If you need fine control on how the mail is sent, for instance if you need to retrieve the message ids, you can inject the underlying client, and use it directly:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="java" class="language-java hljs">@Inject MailClient client;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Three API flavors are exposed:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>the Mutiny client (<code>io.vertx.mutiny.ext.mail.MailClient</code>)</p>
</li>
<li>
<p>the Axle client (<code>io.vertx.axle.ext.mail.MailClient</code>), using <code>CompletionStage</code> and Reactive Streams <code>Publisher</code> - deprecated, it is recommended to switch to the Mutiny client</p>
</li>
<li>
<p>the RX Java 2 client (<code>io.vertx.reactivex.ext.mail.MailClient</code>) - deprecated, it is recommended to switch to the Mutiny client</p>
</li>
<li>
<p>the bare client (<code>io.vertx.ext.mail.MailClient</code>)</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Check the <a href="vertx">Using Vert.x guide</a> for further details about these different APIs and how to select the most suitable for you.</p>
</div>
<div class="paragraph">
<p>The retrieved <code>MailClient</code> is configured using the configuration key presented above.
You can also create your own instance, and pass your own configuration.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="conclusion"><a class="anchor" href="#conclusion"></a>Conclusion</h2>
<div class="sectionbody">
<div class="paragraph">
<p>This guide has shown how you can send emails from a Quarkus application.
The <em>mailer</em> extension works in JVM and native mode.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="configuration-reference"><a class="anchor" href="#configuration-reference"></a>Mailer Configuration Reference</h2>
<div class="sectionbody">
<div class="paragraph configuration-legend">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> Configuration property fixed at build time - All other configuration properties are overridable at runtime</p>
</div>
<table class="tableblock frame-all grid-all stretch configuration-reference searchable">
<colgroup>
<col style="width: 80%;">
<col style="width: 10%;">
<col style="width: 10%;">
</colgroup>
<tbody>
<tr>
<th class="tableblock halign-left valign-top"><p class="tableblock"><a id="quarkus-mailer_configuration"></a><a href="#quarkus-mailer_configuration">Configuration property</a></p></th>
<th class="tableblock halign-left valign-middle"><p class="tableblock">Type</p></th>
<th class="tableblock halign-left valign-middle"><p class="tableblock">Default</p></th>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><a id="quarkus-mailer_quarkus.mailer.from"></a><code><a href="#quarkus-mailer_quarkus.mailer.from">quarkus.mailer.from</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Configure the default <code>from</code> attribute. It&#8217;s the sender email address.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><a id="quarkus-mailer_quarkus.mailer.mock"></a><code><a href="#quarkus-mailer_quarkus.mailer.mock">quarkus.mailer.mock</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Enables the mock mode, not sending emails. The content of the emails is printed on the console.
 Disabled by default on PROD, enabled by default on DEV and TEST modes.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><a id="quarkus-mailer_quarkus.mailer.bounce-address"></a><code><a href="#quarkus-mailer_quarkus.mailer.bounce-address">quarkus.mailer.bounce-address</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Configures the default bounce email address.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><a id="quarkus-mailer_quarkus.mailer.host"></a><code><a href="#quarkus-mailer_quarkus.mailer.host">quarkus.mailer.host</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>The SMTP host name.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock"><code>localhost</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><a id="quarkus-mailer_quarkus.mailer.port"></a><code><a href="#quarkus-mailer_quarkus.mailer.port">quarkus.mailer.port</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>The SMTP port.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">int</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><a id="quarkus-mailer_quarkus.mailer.username"></a><code><a href="#quarkus-mailer_quarkus.mailer.username">quarkus.mailer.username</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>The username.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><a id="quarkus-mailer_quarkus.mailer.password"></a><code><a href="#quarkus-mailer_quarkus.mailer.password">quarkus.mailer.password</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>The password.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><a id="quarkus-mailer_quarkus.mailer.ssl"></a><code><a href="#quarkus-mailer_quarkus.mailer.ssl">quarkus.mailer.ssl</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Enables or disables the SSL on connect. <code>false</code> by default.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock"><code>false</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><a id="quarkus-mailer_quarkus.mailer.trust-all"></a><code><a href="#quarkus-mailer_quarkus.mailer.trust-all">quarkus.mailer.trust-all</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Set whether to trust all certificates on ssl connect the option is also applied to <code>STARTTLS</code> operation. <code>false</code> by default.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock"><code>false</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><a id="quarkus-mailer_quarkus.mailer.max-pool-size"></a><code><a href="#quarkus-mailer_quarkus.mailer.max-pool-size">quarkus.mailer.max-pool-size</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Configures the maximum allowed number of open connections to the mail server If not set the default is <code>10</code>.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">int</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><a id="quarkus-mailer_quarkus.mailer.own-host-name"></a><code><a href="#quarkus-mailer_quarkus.mailer.own-host-name">quarkus.mailer.own-host-name</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>The hostname to be used for HELO/EHLO and the Message-ID</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><a id="quarkus-mailer_quarkus.mailer.keep-alive"></a><code><a href="#quarkus-mailer_quarkus.mailer.keep-alive">quarkus.mailer.keep-alive</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Set if connection pool is enabled, <code>true</code> by default.
 If the connection pooling is disabled, the max number of sockets is enforced nevertheless.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock"><code>true</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><a id="quarkus-mailer_quarkus.mailer.disable-esmtp"></a><code><a href="#quarkus-mailer_quarkus.mailer.disable-esmtp">quarkus.mailer.disable-esmtp</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Disable ESMTP. <code>false</code> by default. The RFC-1869 states that clients should always attempt <code>EHLO</code> as first command to determine if ESMTP is supported, if this returns an error code, <code>HELO</code> is tried to use the <strong>regular</strong> SMTP command.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock"><code>false</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><a id="quarkus-mailer_quarkus.mailer.start-tls"></a><code><a href="#quarkus-mailer_quarkus.mailer.start-tls">quarkus.mailer.start-tls</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Set the TLS security mode for the connection. Either <code>DISABLED</code>, <code>OPTIONAL</code> or <code>REQUIRED</code>.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><a id="quarkus-mailer_quarkus.mailer.login"></a><code><a href="#quarkus-mailer_quarkus.mailer.login">quarkus.mailer.login</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Set the login mode for the connection. Either <code>DISABLED</code>, <code>OPTIONAL</code> or <code>REQUIRED</code></p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><a id="quarkus-mailer_quarkus.mailer.auth-methods"></a><code><a href="#quarkus-mailer_quarkus.mailer.auth-methods">quarkus.mailer.auth-methods</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Set the allowed auth methods. If defined, only these methods will be used, if the server supports them.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><a id="quarkus-mailer_quarkus.mailer.key-store"></a><code><a href="#quarkus-mailer_quarkus.mailer.key-store">quarkus.mailer.key-store</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Set the key store.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><a id="quarkus-mailer_quarkus.mailer.key-store-password"></a><code><a href="#quarkus-mailer_quarkus.mailer.key-store-password">quarkus.mailer.key-store-password</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Set the key store password.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
</tbody>
</table>
</div>
</div>
    </div>
  </div>
</div>

  </div>

  <div class="content project-footer">
  <div class="footer-section">
    <div class="logo-wrapper">
      <a href="/"><img src="/assets/images/quarkus_logo_horizontal_rgb_reverse.svg" class="project-logo" title="Quarkus"></a>
    </div>
  </div>
  <div class="grid-wrapper">
    <p class="grid__item width-3-12">Quarkus is open. All dependencies of this project are available under the <a href='https://www.apache.org/licenses/LICENSE-2.0' target='_blank'>Apache Software License 2.0</a> or compatible license.<br /><br />This website was built with <a href='https://jekyllrb.com/' target='_blank'>Jekyll</a>, is hosted on <a href='https://pages.github.com/' target='_blank'>Github Pages</a> and is completely open source. If you want to make it better, <a href='https://github.com/quarkusio/quarkusio.github.io' target='_blank'>fork the website</a> and show us what you’ve got.</p>

    
      <div class="width-1-12 project-links">
        <span>Navigation</span>
        <ul class="footer-links width-1-12">
          
            <li><a href="/">Home</a></li>
          
            <li><a href="/guides">Guides</a></li>
          
            <li><a href="/community/#contributing">Contribute</a></li>
          
            <li><a href="/faq">FAQ</a></li>
          
            <li><a href="/get-started">Get Started</a></li>
          
        </ul>
      </div>
    
      <div class="width-1-12 project-links">
        <span>Contribute</span>
        <ul class="footer-links width-1-12">
          
            <li><a href="https://twitter.com/quarkusio">Follow us</a></li>
          
            <li><a href="https://github.com/quarkusio">GitHub</a></li>
          
            <li><a href="/security">Security&nbsp;policy</a></li>
          
        </ul>
      </div>
    
      <div class="width-1-12 project-links">
        <span>Get Help</span>
        <ul class="footer-links width-1-12">
          
            <li><a href="https://groups.google.com/forum/#!forum/quarkus-dev">Forums</a></li>
          
            <li><a href="https://quarkusio.zulipchat.com">Chatroom</a></li>
          
        </ul>
      </div>
    

    
      <div class="width-3-12 more-links">
        <span>Quarkus is made of community projects</span>
        <ul class="footer-links">
          
            <li><a href="https://vertx.io/" target="_blank">Eclipse Vert.x</a></li>
          
            <li><a href="https://microprofile.io" target="_blank">Eclipse MicroProfile</a></li>
          
            <li><a href="https://hibernate.org" target="_blank">Hibernate</a></li>
          
            <li><a href="https://netty.io" target="_blank">Netty</a></li>
          
            <li><a href="https://resteasy.github.io" target="_blank">RESTEasy</a></li>
          
            <li><a href="https://camel.apache.org" target="_blank">Apache Camel</a></li>
          
            <li><a href="https://code.quarkus.io/" target="_blank">And many more...</a></li>
          
        </ul>
      </div>
    
  </div>
</div>
  <div class="content redhat-footer">
  <div class="grid-wrapper">
    <span class="licence">
      <i class="fab fa-creative-commons"></i><i class="fab fa-creative-commons-by"></i> <a href="https://creativecommons.org/licenses/by/3.0/" target="_blank">CC by 3.0</a> | <a href="https://www.redhat.com/en/about/privacy-policy">Privacy Policy</a>
    </span>
    <span class="redhat">
      Sponsored by
    </span>
    <span class="redhat-logo">
      <a href="https://www.redhat.com/" target="_blank"><img src="/assets/images/redhat_reversed.svg"></a>
    </span>
  </div>
</div>


  <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.4/jquery.min.js" integrity="sha384-8gBf6Y4YYq7Jx97PIqmTwLPin4hxIzQw5aDmUg/DDhul9fFpbbLcLh3nTIIDJKhx" crossorigin="anonymous"></script>
  <script type="text/javascript" src="/assets/javascript/mobile-nav.js"></script>
  <script type="text/javascript" src="/assets/javascript/scroll-down.js"></script>
  <script src="/assets/javascript/satellite.js" type="text/javascript"></script>
  <script src="https://quarkus.io/guides/javascript/config.js" type="text/javascript"></script>
  <script src="/assets/javascript/search-filter.js" type="text/javascript"></script>
  <script src="/assets/javascript/back-to-top.js" type="text/javascript"></script>
</body>

</html>
